OpenEuphoria

Routines

get

include get.e 
namespace stdget 
public function get(integer file, integer offset = 0, integer answer = GET_SHORT_ANSWER) 

reads from an open file a human-readable string of characters representing a Euphoria object. Converts the string into the numeric value of that object.

Parameters:

1. file : an integer, the handle to an open file from which to read
2. offset : an integer, an offset to apply to file position before reading. Defaults to 0.
3. answer : an integer, either GET_SHORT_ANSWER (the default) or GET_LONG_ANSWER.

Returns:

A sequence, of length two (GET_SHORT_ANSWER) or four (GET_LONG_ANSWER) consisting of:

• an integer, the return status. This is any of:
  • GET_SUCCESS -- object was read successfully
  • GET_EOF -- end of file before object was read completely
  • GET_FAIL -- object is not syntactically correct
  • GET_NOTHING -- nothing was read, even a partial object string, before end of input
• an object, the value that was read. This is valid only if return status is GET_SUCCESS.
• an integer, the number of characters read. On an error, this is the point at which the error was detected.
• an integer, the amount of initial whitespace read before the first active character was found

Comments:

When answer is not specified, or explicitly GET_SHORT_ANSWER, only the first two elements in the returned sequence are actually returned.

The GET_NOTHING return status will not be returned if answer is GET_SHORT_ANSWER.

get can read arbitrarily complicated Euphoria objects. You could have a long sequence of values in braces and separated by commas and comments. For example: {23, {49, 57}, 0.5, -1, 99, 'A', "john"}. A single call to get will read in this entire sequence, return its value as a result, and return complementary information.

If a nonzero offset is supplied, it is interpreted as an offset to the current file position; the file will start seek from there first.

get returns a two or four element sequence; similar to what value returns:

• a status code ( success, error, end of file, no value at all )
• the value just read (meaningful only when the status code is GET_SUCCESS) (optionally)
• the total number of characters read
• the amount of initial whitespace read.

Using the default value for answer, or setting it to GET_SHORT_ANSWER, returns two elements. Setting it to GET_LONG_ANSWER causes four elements to be returned.

Each call to get picks up where the previous call left off. For instance: a series of five calls to get would be needed to read in this sequence: `99 5.2 {1, 2, 3} "Hello" -1` On the sixth and any subsequent call to get you would see a GET_EOF status.

If you had something like {1, 2, xxx} in the input stream you would see a GET_FAIL error status because xxx is not a Euphoria object.

After seeing -- something\nBut no value and the input stream stops right there, you will receive a status code of GET_NOTHING, because nothing but whitespace or comments was read. If you had opted for a short answer, you would get GET_EOF instead.

Multiple "top-level" objects in the input stream must be separated from each other with one or more "whitespace" characters (blank, tab, \r, or \n). At the very least, a top level number must be followed by a white space from the following object. Whitespace is not necessary within a top-level object. Comments, terminated by either '\n' or '\r', are allowed anywhere inside sequences, and ignored if at the top level. A call to get will read one entire top-level object, plus possibly one additional (whitespace) character, after a top level number, even though the next object may have an identifiable starting point.

The combination of print and get can be used to save a Euphoria object to disk and later read it back. This technique could be used to implement a database as one or more large Euphoria sequences stored in disk files. The sequences could be read into memory, updated and then written back to disk after each series of transactions is complete. Remember to write out a whitespace character (using puts) after each call to print, at least when a top level number was just printed.

The value returned is not meaningful unless you have a GET_SUCCESS status.

Example 1:

-- If he types 77.5, get(0) would return: 
{GET_SUCCESS, 77.5} 
 
-- whereas gets(0) would return: 
"77.5\n" 

Example 2:

See .../euphoria/demo/mydata.ex

See Also:

value